Skip to main content

Authentication

Sensitive user information and application-level data are protected by Forio Epicenter. Your application needs to authenticate its users before it can access any of the Forio APIs.

Credential types​

There are two types of credentials in Epicenter:

  • User credentials - allow access to user-specific data. For example, a user without Facilitator privileges can only access the runs they created or the runs that are part of a game in which they are included. A user with Facilitator privileges can access all runs created by users in the group but not those created by users in other groups.
  • Application credentials - allow access to all application-level data. Application-level authentication uses private and public API keys. The most common use case for application credentials is a project that displays a high score list. To construct the list, you must read the score from all runs from all users from all groups in the project. No single user has access to this information.
learn more

For detailed descriptions of the authentication credential objects, read Authentication entities.

Managing session​

The two most common session types are user session and admin session. In Epicenter, a session always resides on the server side.

The JS libraries provide functions to facilitate storing the session on the client side for faster access. For details, read the Local session topic in the Authentication adapter reference.

User session​

A user logs in with credentials called handle and password. If they log in without a group, they have a session but few rights. Almost everything needs a group permission. If a user logs in with a group membership, their group permissions are stored in the session.

User roles​

The user's permissions are defined by their role in the group, indicated by the groupRole property. Possible group roles are:

  • Facilitator - helps to run the simulation.
  • Reviewer - can see everything a facilitator can but cannot edit anything.
  • Participant - participates in the simulation as a player.
  • Leader - a participant with some additional permissions.

Admin session​

When an admin logs in without an account, they also have very few permissions. Once they select an account, they are granted account permissions. These permissions are stored in the admin session.

Admin roles​

The admin's permissions are indicated by the teamAccountRole property. The roles include:

  • Author - can create simulations.
  • Support - provides support for the users.

Session context​

When a user logs in without a group or an admin without an account, there are two possible scenarios:

  • If the user belongs to only one group or the admin to only one account, that group or account is chosen automatically as the session context.
  • If the user belongs to many groups or the admin to many accounts, a flag is set to True in the session object:
learn more

For the complete description of the Session object, read Session in the Developer reference.

Switching context​

If the user switches to another group or the admin switches to another account, the session must be updated.

tip

To update a user or admin session, call the regenerate() function of the Authentication adapter.

Authentication errors​

If an error occurs during authentication, the Forio API returns a 401 HTTP Response status and a string error code.

Here is a list of the most common error codes and their meaning:

  • AUTHENTICATION_ACCOUNT_TOMBSTONED: The account has been requested for deletion.
  • AUTHENTICATION_BLACKOUT: Too many failed authentication attempts. Try logging in again after the blackout elapses.
  • AUTHENTICATION_BLOCKED: The account has been blocked or deactivated. Contact Forio.
  • AUTHENTICATION_EVAPORATED: The session no longer exists on the server. You need to re-login.
  • AUTHENTICATION_EXPIRED: The session expired.
  • AUTHENTICATION_GROUP_EXPIRED: The group is no longer active. Contact the provider of the simulation.
  • AUTHENTICATION_GROUP_TOMBSTONED: The group has been scheduled for deletion.
  • AUTHENTICATION_INVALIDATED: The authentication is no longer valid. For example, the user has been assigned to a new group and needs to re-login.
  • AUTHENTICATION_NOT_VERIFIED: The email address for the user or admin has not been verified.
  • AUTHENTICATION_PROCESS_ERROR: Server-side error.
  • AUTHENTICATION_PROJECT_TOMBSTONED: The project has been scheduled for deletion.
  • AUTHORIZATION_FAILURE: Authentication failed. Check your credentials.